1) Getting Started
Once you have purchased a copy of perlQuestionnaire, you will be given a link that allows you to download the current version. Depending on your operating system, you should grab one of the following packages:
Microsoft Windows
Download the file perlQvX_X.zip and use a program such as to extract the files. You should upload or place this entire hierarchy onto your web server. It will unpack into a directory named 'perlQ'. You will need to know how to access this directory on the web to properly install the script.
NOTE: If you are using Windows XP, it has built-in support for .zip files. Simply use the compressed folder feature of Windows XP to extract the files.
Unix, Mac OS X
If you are using a Unix based operating system (Linux, BSD, Mac OS X, etc.) you will need to download the file perlQvX_X.tar.gz. Once you have retrieved this file, you should place it in a directory on your web server and enter the following commands:
gunzip perlQvX_X.tar.gz
tar xvf perlQvX_X.tar
It will unpack into a directory named 'perlQ'. You will need to know how to access this directory on the web to properly install the script.
1.1) Automatic Installation
Once you have unpacked the program as detailed above, you can now begin the process of automatic installation. You must perform the following steps in the order they appear below:
- When unpacking the files, they will all be placed in appropriate locations within a base directory of 'perlQ/'. Move or Upload this directory onto your web server into a location accessible from your browser.
Note: It is very important that you upload the .cgi program files in ASCII mode and upload any image files in BINARY mode. Many FTP programs have an automatic detection scheme which should work. However, failure to use ASCII mode to upload the .cgi files will cause them to give an error message.
NOTE ON UPGRADING: If you are upgrading from a previous version of
perlQuestionnaire, we recommend backing up your current version in case you
have any problems. Be careful if you have made changes to your current
version. For instance, do not erase any templates you may have created or
modified and if you have changed any other files in perlQ, your
modifications may be lost if you have not properly backed them up to another
directory. If you encounter any problems with the automatic upgrader (it
can update any prior version) please let us know.
- If perlQ is being hosted on a Unix based machine, you must change the permissions of the file 'perlQ/perlQMod/DBInfo.cgi' so that your web server can write it. To do this, you must telnet, ssh or ftp into your machine and issue a 'chmod' command to change the permissions. To do this, login and go to the perlQ/ directory of your installation. Issue the following command:
chmod 766 perlQMod/DBInfo.cgi
Furthermore, you should check the permissions on your files if you are on a Unix server to make sure all of the .cgi files are executable. The following command from the same directory as above will also properly enable execution of these files:
chmod 755 *.cgi admin/*.cgi
- Load up the installation page by opening your web browser and going to the following URL:
http://www.yourhost.com/path/to/perlQ/install.cgi
You must modify this URL to include your actual domain and then the 'path/to' must be changed to the location on your web server where you have placed your perlQ program.
- You will now see a page in your web browser that looks like:
 | Figure 1.1-01 - Automatic Installation |
The Language option will only appear if you have multiple administrative language packs installed. If so, you can install in that language and it will become the admin and default language for perlQ.
You must fill in the correct MySQL configuration variables. If you are unsure of any of the MySQL configuration parameters, please consult your web hosting provider.
- MySQL Hostname
In most cases, the MySQL Hostname should be set to 'localhost'. This is the most common configuration, in which both the MySQL server and the web server are running on the same machine.
In some cases, your MySQL database may be running on a different machine from your web server. If this is so, you must enter the hostname of the MySQL database server here.
- MySQL Username
MySQL Password
Logging into a MySQL database server requires a username and password. This may be different from the username and password you use to access your web server.
- MySQL Database
perlQuestionnaire needs to know the MySQL database to which it should add the configuration and survey tables. If you are able to create databases, you may wish to create one named 'perlQ'. In either case, please enter the name of your MySQL database into this box.
- Installed in cgi-bin
perlQ needs to know whether you have installed it into a cgi-bin style executable directory or an ExecCGI setup. The former executes any file in the directory, whereas the latter executes only .cgi files. You should see a Green check mark if it is installed into a cgi-bin, and a Red x mark if not. It is more efficient to install it outside of your cgi-bin, if your server is capable of that. Answer this question according to what you see, where a green check means yes and a red x means no. You can read more about this configuration parameter.
If you are upgrading an existing set of perlQ tables to the newer version, you will also need to supply the Admin Password to prove that you are authorized to make this change. This password will be the same one you have been using to login to the perlQ admin control panel. You will not need to supply the Installed in cgi-bin parameter during an upgrade. perlQ will use the value that already exists in your database.
Next to the upgrade button you will notice there is an option to 'Backup Database'. We recommend you click on this button before upgrading. Once clicked, you will be prompted to download a .perlQ file which contains all of the data from your perlQ installation. This file can then be used to restore your database in the very small chance something goes wrong with the upgrade.
You may now click the 'Install' or 'Upgrade' button depending on which you wish to do and perlQuestionnaire will automatically perform the requested action, alerting you to any errors it may encounter.
- Upon successful installation, you will see the following screen:
 | Figure 1.1-02 - Automatic Installation : Success |
- If all of the items say success, perlQ has been correctly installed. Once you have checked to see that it is working, you need to change the permissions of your DBInfo.cgi configuration file back to normal, so that no one else may modify your database parameters. To do this, issue the following command, much like you did before:
chmod 644 perlQMod/DBInfo.cgi
- It is crucial that you also remove the install.cgi file once you have successfully setup perlQ. You need to delete the file 'perlQ/install.cgi' possibly using the following command (if you are still in the perlQ/ directory of your installation):
rm install.cgi
It is important to do this so that no one else may access this file in the future and create a new installation of perlQ without your authorization.
- Click the "Proceed to Admin" button shown in Figure 1.1-02 which will take you to Logging in as Administrator for the first time.
If for some reason the automatic installation fails or you wish to do a manual installation, you can follow the steps outlined in section 7.2 - Manual Installation.
1.2) Logging in as Administrator
When logging into the perlQuestionnaire administration section, you will be presented with a screen that looks like:
 | Figure 1.2-01 - Admin Login |
For the first time...
If you have just installed perlQ and this is your first time logging in, you should enter the default login password, which has been configured as 'password' (without the quotes).
CHANGE YOUR PASSWORD
Since this is your first time logging in, you should immediately change the administration password. Failure to do so leaves your perlQuestionnaire installation open to anyone who knows our default password or tries to guess. This means anyone can create, modify or remove surveys from your site without your permission. To change your password, click on the 'Configuration' tab in perlQ administration. For further information, see Changing Administrator Password.
Again and again...
To access the perlQ Administration panel in the future, simply point your web browser to:
http://www.yourdomain.com/path/to/perlQ/admin/index.cgi
You obviously must modify the above URL to contain your actual domain name and the path to where you have installed the perlQ program on your web server.
1.3) Administration Panel Sections
After logging in to the administration panel, you will find 5 tabs at the top (the current section will be highlighted):
- Main
This link will return you to the Survey Overview that offers quick access to taking, editing, previewing or viewing the results of any specific survey. This is the page that you see when you first login.
- Survey Editor
This link directs you to a form for modifying an existing survey or adding a new one. From here you can also access the question editor. Any modification of a survey must be done through this section.
- Survey Results
As people complete your active surveys, their results will be available through this link. You will be able to view summaries, statistics and remove any specific survey submission.
- Configuration
This area of the administration allows you to alter the way the perlQ admin panel works. For instance, how many survey results are displayed per page, what template should be used by default, etc.
- Log Off
Click this tab when you are done using the perlQuestionnaire administration panel. Alternatively, quitting out of your web browser will end your session as well.
2) Survey Overview
 | Figure 2-01 - Survey Overview |
The Survey Overview page displays each survey that has been created. To the left of the survey you will find an image that describes the state of the survey. You can manually activate and deactivate a survey. The following images may appear next to each survey:
- ACTIVE
This image appears any time the public is allowed to take your survey. This means that it has been manually activated and if a starting or ending date has been specified, it is within those bounds.
- PENDING
This image appears when a survey has been manually activated, but the public is not yet allowed to take the survey as it has not reached the starting date.
- EXPIRED
If a survey is still in the system as active, but the ending date has since passed, you will see this image appear. Users are no longer allowed to take the survey, but you may wish to manually deactivate it.
- NOT ACTIVE
This image will appear if you have manually deactivated a survey. No users will be allowed to complete the survey in this state.
A link to an individual survey's results is provided to the right of the survey's name. This link will also inform you of how many responses to that survey currently exist. Quick links to edit or preview the survey are also available. You may find the following items listed below each survey, depending on the active status of that survey:
- Description
This contains any survey description you have entered for this particular survey.
- Active Dates
This shows any date restrictions placed on the survey, such as a starting date, ending date or both. The survey will only be shown according to those dates when 'Active'.
- Link to Survey
This is the link visitors must follow in order to complete the survey. You can also use the portion of this URL after the domain name inside of a server side include call to import the survey into an existing page.
- Public Results
If you have chosen to make survey results public, a link to the public survey results will be made available here. You can use this to point your users to the results if you wish.
You will notice that an image will appears next to the text "Survey Overview". This image is fetched from our system every time you login. Should we release a security fix or product enhancement, you will be notified via this image (and possibly via email as well). Simply click on the image if you notice there is an update waiting and you will be able to login and download the patch or new version. Otherwise, it will normally state that no updates or announcements exist for the current version.
3) Survey Editor
The survey editor is where all modification and configuration of a specific survey is to be done. This is also where you should go if you wish to add a new survey, remove a survey or edit questions. At the top of the Survey Editor you will see a selection box allowing you to select the specific survey you wish to manage. It will appear something like:
 | Figure 3-01 - Survey Editor |
Once a specific survey has been selected, the page will automatically refresh and you will see the:
 | Figure 3-02 - Survey Editor: Survey Selected |
You now have access to the following actions which can be performed on this survey:
- Edit Questions - Click on this button to be taken to the question editor. From there you will be able to add, modify and delete any questions and answers from the survey you have created.
- Preview - Clicking on this button will popup a new window that allows you to preview your survey without actually submitting any results. Any question requirements are still enforced, so it will behave as would be expected for the final users. You can preview a survey when it is deactivated.
- Activate or Deactivate - When your survey is created, it defaults to a Deactivated state. This allows you to fully complete and test the survey without users being able to access it. Once your survey is finalized and ready to go live, you should activate the survey by clicking the Activate button. Any starting and ending dates will still be enforced on an active survey. You can stop any submissions on the survey by clicking the Deactivate button on an active survey.
- Export - You can export a survey, along with all questions, into a single file which will allow you to swap this file with another user of perlQ. That person can then import the survey using the form at the bottom of the Survey Editor. Survey Results will not be included in this export. If you wish to back those up, you should check out the Configuration tab.
- Delete - To remove a survey and all related questions and results, click on this button. You will be prompted with a JavaScript alert box, and if you click OK the survey will be removed from the system. You cannot undo this action.
3.1) Adding or Modifying a Survey
The next portion of the Survey Editor contains the form used for adding and modifying surveys within perlQuestionnaire. There are two interfaces for this form, both of which are shown below. The Basic interface gives you quick access to the most important details of survey creation. If you wish to take full advantage of all that perlQuestionnaire offers, you will definitely want to use the Advanced interface, however.
 | Figure 3.1-01 - Survey Editor: Basic Interface |
 | Figure 3.1-02 - Survey Editor: Advanced Interface |
If a survey has been selected within the Survey Editor, the setup for that survey will be placed into the "Add/Modify a Survey" form and made available for modification. Once you have modified the setup, you can either click the "Add" or "Modify" button. Clicking "Add" will create a new survey with the values you have entered, while clicking Modify will simply update the existing survey with the new configuration. The setup in both basic and advanced mode is explained in detail below.
FIELDS APPEARING IN BASIC AND ADVANCED INTERFACES:
- Survey Name
This field is used within the perlQ admin to refer to the specific survey that you are creating or modifying.
This value can also be substituted into survey templates using the marker ::SURVEYNAME::. In the default perlQ template, this value appears in the title bar of the user's browser.
- Survey Template
This field allows you to select the template that you wish for this survey to appear in. You can download more templates for perlQ at <http://www.chumpsoft.com/products/perlq/.
The program checks in your perlQ/templates directory in order to determine what templates are available for use in your survey program. Removing the files from this directory will cause perlQ to stop functioning properly.
The values you can use inside of your template that perlQ will recognize are:
- ::SURVEYNAME:: - perlQ will replace this text with the Survey Name. In the default template, this is placed in the <TITLE> tags.
- ::CONTENT:: - perlQ will replace this text with the survey questions and answers. This tag is required in order to have the survey questions and answers appear on the page.
- ::JSCRIPT:: - This will import any required JavaScript into the template. The only time this is needed is if your results are publicly viewable, so that the survey can popup extra results over the configured limit for textfields and other inputs. You are free to leave this out if you will not be offering public results in your template.
- Survey Language
perlQ allows you to create surveys in different languages. If this select box appears on the survey editor page, then you have more than one language available for creating surveys. Simply select the language you wish to use for this survey from the list. Although you control almost all data input to define the language, selecting the appropriate language from this list will cause any error messages and buttons to appear in your language as well as select the correct character set for the browser to use.
You may also wish to read about creating your own translations or to find more translations by users such as yourself, you can check http://www.chumpsoft.com/products/perlq/!
- User Restrictions
These can be used to attempt to limit the number of submissions to one per user per survey. They are also effective in stopping accidental duplicate submissions and validating the user's e-mail address. They aren't, however, 100% effective and a determined user will still be able to make multiple survey submissions. You are allowed to select any of the following three options. Selecting none of them will allow any user to submit the survey as many times as they wish. You can select multiple restrictions to enforce multiple rules.
- Unique IP Address - You can use a user's IP address as one method of blocking multiple survey submissions from the same computer. This is not a 100% guaranteed method and it can be fooled. In some cases, it may deny a legitimate user the ability to complete the survey if two different users are on the same IP address, and in other cases a user could simply change computers to submit the survey twice. In any case, it does provide protection against accidental duplicate submissions or someone who is not intent on submitting the survey more than once.
- Cookies - Using these restriction, perlQ will attempt to place a cookie in the user's browser each time they complete a survey. If perlQ detects they have already completed the survey, they will not be allowed to make another submission. Using this restrictions requires them to have a cookie-capable browser to complete the survey as it also checks to make sure they don't have cookies turned off. This is not 100% protection and the program can still be fooled into taking multiple survey submissions from the same user.
- Verified Email - This is by far the most effective restriction. It requires that every person who completes the survey also supply an e-mail address which they are then forced to validate. It is still not 100% effective and cannot guard against users who have multiple e-mail addresses and wish to submit several surveys, but it does provide you with a working e-mail address with which you can contact survey respondents. This option only appears if you have defined a Sendmail Path or SMTP Server in the Configuration panel.
- Description
This field contains text that will be displayed on the Survey Overview page which lists all of your active and inactive surveys. It is only there if you wish to provide a brief summary of the purpose or contents of this survey.
FIELDS APPEARING IN ADVANCED INTERFACE ONLY:
- Instructions
This field will be displayed at the top of the first page of the survey and can be used to explain what the survey is, how it should be taken or any other information you wish to communicate to the user. You can feel free to use any HTML markup you wish within this textarea and it will be shown as entered when a user begins to take the survey.
Some information you may wish to display here are things such as User Restrictions so the user knows if they will need to have cookies enabled, supply a valid e-mail, etc.
- Starting Date
- Ending Date
perlQ provides a way in which you can set up surveys with specific starting and ending dates. If you are not using starting and ending dates, you must manually activate and de-activate the survey when you wish for it to be available or taken down. The starting and ending dates allow you to activate the survey and have perlQ determine whether the user is allowed to access it based on the time. In this way, you don't have to be around at midnight if you wish for the survey to expire at the end of a day.
Starting Date - By setting these fields to a valid date and time, perlQ will not allow anyone to fill out the survey before that specific time.
Ending Date - By setting these fields to a valid date and time, perlQ will not allow anyone to fill out the survey after that specific time.
You do not have to fill in both of the fields to use one of the functions. For example, if you wish to manually activate the survey, but have a pre-defined end time, you only have to set the Ending Date.
- Survey Width
When perlQ places the survey inside of your template, it embeds the survey within a table. The Survey Width parameter allows you to control the width of the table in which your survey appears.
In some cases, the text or style of some of your questions or answers may cause the survey table to be expanded outside of your defined Survey Width. Therefore, this field is more useful for specifying a width when the table is smaller than you would like it to appear, and wish to expand it.
- Answer Indentation
This parameter specifies how many pixels your answers will appear indented from the leftmost text of each question. Leaving this blank or setting it to 0 will cause the answers to line up with the questions.
- Auto Numbering
If Auto Numbering is set to "Yes", each question will have a number appear in front of it. If you set this to "No", no numbers will appear in front of the questions and you will be responsible for placing the numbers in each individual question if you wish to have them.
- Question Text Style
- Answer Text Style
- Error Text Style
The goal of perlQ was to allow you to design your survey to look any way you wish. To do this, we have offered options on the way your questions, answers and error messages can appear.
In these fields you may enter any CSS style definition that you wish to have applied to all question, answer or error text in the survey. You can also modify the question or answer text style individually when adding or modifying that question. The style of an individual question or answer will override the survey wide styles you define here. For example, if you wanted to have your error messages all appear in a red, Arial font of size 12px, you would enter the following into the Error Text Style field:
color: red; font-style: Arial; font-size: 12px;
This would then cause your error messages to appear as:
Please complete this question.
The style definitions will be placed inside of the <TD> that surrounds the question text or error text. Your answer text style will also be applied to <SELECT> fields allowing you to control the appearance of the text within those input items. You will also be able to override survey-wide defaults for Question Text Style and Answer Text Style within each question setup itself. Error Text Style can only be defined on a survey-wide basis.
To find out more about CSS styles, go to .
- Answer Input Style
This field allows you to enter any CSS style definition that you wish to have applied to the table cells (<TD>) that surround answer input fields such as radio button, checkboxes, select boxes and text fields. It should be noted that this style will apply to the surrounding cells, not the input fields themselves. To affect the input fields themselves you should read about Text Input Style for textfields and textareas and Answer Text Style for select boxes (single and multiple). Radio and checkboxes cannot currently be altered using CSS.
You will also be able to override survey-wide defaults for Answer Input Style within each question setup itself.
- Text Input Style
In this field you may enter any CSS style definition that you wish to have applied to all text field answer inputs (text fields and text areas). If you wanted all of your 'Other:' field text fields and all of your text area inputs to have a width of 300 pixels and no shading, you could set this to:
width=300px; border-left: 1px solid black; border-right: 1px solid black; border-top: 1px solid black; border-bottom: 1px solid black;
That would yield text fields throughout the survey that looked like:
The style definitions will be placed inside of the individual input fields for each answer input they apply to. You will also be able to override survey-wide defaults for Text Input Style within each question setup.
To find out more about CSS styles, go to .
- Email From
- Email Subject
- Verification Email
Should you choose to restrict survey results based on verified email addresses you will also need to fill in the following three fields. These fields control the appearance of the email that is received by the user once they complete the survey, requesting for validation of their email address.
- Email From: - This data will appear in the 'from' line of the email message that the user receives asking for their email validation.
- Email Subject: - This is the subject of the verification email that the user will receive.
- Verification Email: - This is the body of the message that contains all of the information necessary for the user to validate the e-mail address they supplied and thus complete the survey. The valid template fields for this email message are ::SurveyName::, ::ConfirmPassword:: and ::ConfirmURL::. These values will be replaced with the name of the survey the user just completed, the confirmation password (automatically generated by perlQ) and a direct link to the script, so that with one click they can finish the survey. A sample of what you may wish to enter in this field is supplied as the default value for a new survey.
- Upon Completion
The Upon Completion option allows you to determine where the user will be sent once they have completed your survey. You may choose between the following options:
- Display the completion notice shown below
By default, this field is set to display a default completion notice stating that the survey has been completed. You can change the notice by modifying the Completion Notice field. The user will be shown this information once they have successfully completed your survey. Feel free to include a link to the survey results on this page by placing it in the Completion Notice.
- Redirect user to the survey results page
perlQuestionnaire now allows you to make the results for a specific survey publicly viewable via the Survey Results option. If you have chosen to make your results public, you may also elect to have the users redirected to these results once they complete your survey. To do so, simply select this option.
- Redirect user to the URL specified below
Selecting this option and completing the Redirect URL field will cause your users to be sent to the web page of your choice once they have completed the survey.
- Redirect user to their individual survey response summary
Starting with version 2.2, you can display a user's survey responses to them at the end of the survey. Select this option and they will be shown a listing of each question and answer that they have completed in your survey.
- Completion Notice
This field is the message that will be displayed to the user once they have successfully completed the Survey. You are free to use any HTML you wish and it will be shown in the ::CONTENT:: area of the survey template as entered.
- Redirect URL
perlQuestionnaire allows you to redirect a user to any specific URL you choose Upon Completion. If you have set the "Upon Completion" field to "Redirect user to the URL specified below", simply enter the destination URL into this field. Once a user has successfully completed the survey, they will be redirected to that location.
NOTE: This URL should be an absolute, beginning with http:// or https://
- Response Notice
Starting with version 2.2, perlQuestionnaire is now capable of sending email notices each time a survey response has been completed. The options are:
- Do not send any notification email - This is the default option. If selected, no email notifications will be sent upon survey completion.
- Email text notice of response to addresses listed below - If selected, the email addresses listed in Response Email will receive a short text message each time a survey has been completed. It will list the survey title, date of completion, IP address and a link to the full results.
- Email HTML summary of response to addresses listed below - If selected an HTML-formatted message will be sent to the email addresses listed in Response Email that includes the user's response to each question in the survey.
- Response Email
The email address (or multiple addresses separated by commas) listed in this field will receive the Response Notice for each survey submitted.
- Survey Results
perlQuestionnaire allows you to make the results for a specific survey publicly viewable. To do so, simply set this option to one of the "Make survey results public" options. If this option is set, users will be able to see the results for this survey. A link will be shown on the survey overview page of the admin which you can use to let visitors get directly to the results.
There are two options when making your survey results public. The first option simply supplies you with a URL that you can place anywhere you wish allowing visitors to view the survey results (such as the Completion Notice). The second option (include button on survey) will place a "View Results" button next to each Next or Submit button that occurs on your survey. This allows your visitors to easily bypass the survey and get straight to the results, much like many polling scripts usually work.
Either public results option also allows you to set the Upon Completion action to redirect users to this publicly viewable statistics page once they have successfully completed the survey.
PLEASE NOTE: If you deactivate your survey, it will deactivate the ability for the public to reach your statistics. If you wish to stop users from submitting results, but still allow them to view results, you must set a specific ending date for your survey and leave it active.
 | Figure 3.1-03 - Customizing Public Survey Results |
- Results Table Width
perlQ gives you a wide range of controls over the look of public survey results. You can define the width of your results boxes using the Results Table Width parameter. It should be defined in pixels (commonly between 400 and 800). perlQ will automatically calculate the maximum length for the resulting bar graphs, which are 110 pixels less than the width entered here.
The default for this field is 500 pixels. In some cases, the text or style of some of your questions or answers may cause the survey results table to be expanded outside of your defined Results Table Width.
- Results Border Style
This field controls the table enclosing the results. You can set the color of this table using the background-color CSS property. It also controls the color of any text and links appearing in the border (using the color CSS property). Since this style will be placed inside any links in the border, you can also specify things such as text-decoration to control link highlighting, etc. By default, the border has a purple background color with white colored text and links:
background-color: #333366; color: #FFFFFF; text-decoration: none;
You may, in fact, include any style definition here, and it will appear in the <TD>'s that create the table border as well as any <A> anchor tags for links such as "See More..." or page numbers.
To find out more about CSS styles, go to Zvon.org CSS1 Reference.
- Results Answer Style
This field controls the appearance of rows in your results table that contain the selected answers. You can change either of these using the background-color or color CSS properties. Furthermore, this style will be applied to the 'Textfield Results' link should it appear. By default these rows have a white background and purple text:
background-color: #FFFFFF; color: #333366;
You may, in fact, include any style definition here, and it will appear in the <TD>'s that create the answer rows as well as any 'Textfield Results' link.
- Results Stats Style
This field controls the appearance of rows in your results table that contain the statistics (how many people chose a specific answer, bar graph, etc.). You can change either of these using the background-color or color CSS properties. Although the results bar graph appears in this row, the style of the bar graph is controlled using the Stats Graph Style. By default these rows have a light-blue background and purple text:
background-color: #DDEEFF; color: #333366;
You may, in fact, include any style definition here, and it will appear in the <TD>'s that create the stats rows.
- Stats Graph Style
This field controls the appearance of the bar graph within your survey results. You can control the color of it using the background-color CSS property, and even the thickness of the bar using the height directive. You may also wish to look into using background-image to create 3-d styled bars. To control the background color that appears behind the bar, you should look into the Results Stats Style. The default for this field is:
background-color: #333366; height: 8px;
You may, in fact, include any style definition here, and it will appear in the <TD> that creates the result bar. The bar is nothing but a transparent gif that can be styled howvever you wish.
- Submit Button Style
- Results Button Style
- Next Button Style
With the addition of button styles in perlQ 2.1, you can now customize every aspect of the survey. No longer are you restricted to using the default button styles for "Submit", "Next" and "View Results". With the introduction of the Submit Button Style, Results Button Style and Next Button Style you can now control all buttons that users may view. The following fields will help you to customize these buttons:
- Text - When used with an Image, this text will become the ALT tag for your button. Otherwise, the text that you type in here (such as 'Submit' or 'Next') will become the label for your button.
- Width and Height - When used with an Image, these fields will control the width and height of your image, as attributes in the tag. If you are not using an image, we will apply correct CSS definitions to your text button to make it this size. These fields are defined in pixels.
- Image - If you are not a fan of boring looking submit buttons, you can now use any image on your web site as the next, submit or results button! Simply enter the URL to your image in this box and it will be used as the button.
Please note that the Next Button Style will only appear if you have a multi-page survey and the Results Button Style will only appear if you have the Survey Results field set to 'Make survey results public (include button on survey)'. Furthermore, if you do have public results and a multi-page survey, the Next Button Style will also be used on the page-by-page view of your public results.
Advanced CSS Trick
Some of you may be wondering why we left out CSS customization of the button when it is readily available for all other areas of perlQ. We felt that the Text/Size/Image fields were more useful on a day to day basis for most users' needs. However, we have a little trick for those of you who want to customize your button CSS.
When you leave the Image portion of your Button Style blank, the Text field will be included in the VALUE="" portion of your <input> tag. Normally, if you put 'Submit' as the Text, this would result in:
<INPUT TYPE=submit VALUE="Submit">
If you were instead, however to enter into the Text field something like 'Submit" STYLE="color: red;' you would achieve the following:
<INPUT TYPE=submit VALUE="Submit" STYLE="color: red;">
It is important to note that you need to include a double quote after the text you wish to have appear on your button and then leave off the last double quote from the end of your STYLE definition. Once you have the basic format down, it is easy to add any styles you want! If you have any further questions on this, simply contact chumpsoft support and we will be happy to help.
3.2) Previewing a Survey
perlQuestionnaire offers the ability to preview any survey that you have created. It will appear exactly as a user would see the survey. Any answers you supply will be checked for validity (such as whether the field is required, how many answers should have been supplied, and so on).
You can preview a survey at any time, whether or not it is active. This allows you to create and test a survey extensively before making it available to users. The survey preview from several areas of the perlQuestionnaire administration panel.
The most common way to access the survey preview is from the Survey Overview page. This is the page that is first shown when you log into the administration area of perlQuestionnaire (shown in Figure 2-01). Each survey is listed along with a purple image that says "PREVIEW". Simply click on that link to take a look at how a user would see this survey.
You can also preview a survey by clicking on the "Preview" button in the Survey Editor (shown in Figure 3-02) after selecting a survey from the list. The preview is also available from the Question Editor (shown in Figure 4-01).
3.3) Survey Activation/Deactivation
perlQuestionnaire allows you to manually activate and deactivate surveys within the administration panel. Any active survey that is within its defined starting and ending dates can be completed by users. If you wish to stop a user from taking the survey, or if the survey is currently in development, you should set the status to "Not Active" in order to prevent users from completing it. The survey may still be previewed from the administration panel at any time.
To activate or deactivate a survey, enter the Survey Editor and select a survey. Once a survey has been selected (as in Figure 3-02) a button will appear allowing you to either activate or deactivate the survey, depending on the current state.
3.4) Deleting a Survey
Once a survey has been completed and you no longer desire any of the results, you may wish to delete the survey and all connected data (questions, results, etc.) from the system. To remove a survey from the system, enter the Survey Editor and select a survey. Once a survey has been selected (as in Figure 3-02) click the Delete button to remove the survey. A prompt will appear asking you to verify the deletion. This process cannot be un-done.
Please keep in mind that you do not have to delete a survey in order to stop users from completing it. You may simply deactivate the survey, allowing you to continue to have access to the results and statistics.
3.5) Exporting a Survey
perlQuestionnaire offers you the ability to export a survey along with the questions and answers you have defined. You can then share this file with a friend, a colleague or even the entire perlQ user community by sending it to support@chumpsoft.com. Simply select a survey on the Survey Editor page and you will see an 'Export' button. Click on this button and your browser will prompt you to save a file ending in .perlQ. The filename generally begins with the word surveyswap and includes the survey id number. You or someone else can now import this survey using the form at the bottom of the Survey Editor.
We have implemented this feature because we know it can take a lot of time and effort to develop a good survey, and some users may enjoy sharing their surveys with others. We welcome any contributions you may offer!
Please note that survey exports do not contain any survey results or user data. If you wish to share or backup that information, you should read more about backing up the database for perlQ.
3.6) Importing a Survey
 | Figure 3.6-01 - Import a Survey |
This form offers you two options for importing a survey:
- Upload Data File
This field offers you the ability to import a survey from a file you have on your hard drive. Simply click the "Browse..." button and locate an exported perlQ survey file. Once you have chosen this file, click on the "Import Survey" button and the new survey will appear in your perlQuestionnaire interface, assuming there are no errors with the file.
- Fetch From URL
This field gives you the power to import a survey from any URL. You must enter a full URL (starting with http://) to the location of a valid exported perlQ survey file. perlQ will then attempt to fetch and import this survey. This is very useful for importing surveys that may be offered at chumpsoft. If also comes in handy if your export file is too large to place in the upload field or file uploads are not working on your machine.
Note: Perl requires you to have installed the module in order to retrieve items via a URL.
The following briefly explains the behavior of the import feature in perlQ:
- When imported, all surveys will be "Not Active" and show a current-day creation date.
- The imported survey will attempt to locate the template it was exported with. Failing that it will use the first template it finds in the following order: the configured default template on your perlQ installation, the 'default' template distributed with perlQ or the first template it can find in the templates directory.
- Nothing in your perlQ installation will be overwritten or deleted by an imported survey. You can import the same survey multiple times and it will simply create multiple instances of that survey, along with all of the associated questions and answers.
- Imported surveys do not retain the original survey or question ids they were exported under.
If you are looking to import survey results, maintain survey ids or restore your entire database, you will want to read about restoring the database.
4) Question Editor
After creating a survey with the Survey Editor and selecting it as shown in Figure 3-02 you will see a button that says 'Edit Questions'. By clicking on this button, you will be taken to the question editor for this survey. At the top of the page will be the name of the survey and a list of questions for this survey. An example list of questions is shown below in Figure 4-01:
 | Figure 4-01 - Question Editor: List of Questions |
Using the above interface, you can Edit, Delete, Re-Order or Preview the questions contained in this survey. There is also the ability to create and remove page breaks from within the question order.
4.1) Adding or Modifying a Question
Below the question list, you will find a form that can be used to add a new question or modify an existing question for the selected survey. To edit a question, and have the existing values pre-populated into the form, you should select the question from the question list and click the Edit button. If there are already values in the form and you wish to start over and add a new question, simply click the "Clear Form" button at the bottom of the form to add or modify a question.
The form to add or modify a question will differ depending on what question type you have selected. Therefore, the screenshots below depict a typical form for adding or modifying a question with a type of radio button. There is also an advanced and basic display of the question editor which will either show or remove some of the optional fields for that question type. Although not all fields are shown in the screenshot below, all of them are documented both below this screenshot and within the program by clicking on the question mark icons.
 | Figure 4.1-01 - Question Editor: Radio Button Advanced |
If a question has been selected within the question list, the setup for that question will be placed into the "Add/Modify a Question" form and made available for modification. Once you have modified the setup, you can either click the "Add" or "Modify" button. Clicking "Add" will create a new question with the values you have entered, while clicking Modify will simply update the existing question with the new configuration. The setup in both basic and advanced mode is explained in detail below.
- Question
The value of this field is what the user will be asked when completing this question in the survey. You are free to type either text or HTML into this field and it will be displayed on the survey exactly as you have entered it.
If you wish to provide extended instructions for a specific question or group of questions, you may wish to look into the Instruction Text field which appears in the advanced "Add/Modify a Question" form.
- Content Name
This appears only for the "HTML Content" question type and is used simply as an identifier for the question within your perlQ admin panel. It will not be displayed within your survey.
- Type
The type of the question is one of the more important fields to select. Every type has its own distinguishing characteristics and will govern how your answer choices appear to the person taking the survey.
- Radio Buttons - A radio type question allows the user to select only one of a pre-defined list of answers for the question. All answers will be displayed for the user to read. You may associate a textfield with any of the choices you create, allowing the users to enter a custom or 'Other' answer in their own words.
- Check Boxes - A checkbox type, like the radio type, displays all of the answers for the user to read. However, should you choose the checkbox type, the user is allowed to select multiple responses. Once this type is selected, another option (Number of Answers) appears that you can configure. This allows you to optionally force the user to fill in a fixed number of answer boxes, at least X number of boxes, at most X number of boxes. You may associate a textfield with any of the choices you create, allowing the users to enter a custom or 'Other' answer in their own words.
- Text Field - A text input field is provided that allows the user to enter an answer in their own words. You can supply a Default Answer when this question type is selected. Users may not enter line breaks into their answer with this type of response.
- Text Area - A text input area, like the text input field, provides a spacious field for the user to enter text as an answer. Breaks or carriage returns are allowed for textareas as well as a Default Answer.
- Select Box - A select box allows the user to choose one answer, similar to the radio type. Unlike the radio type, a choice can be made to make an answer un-selectable. This allows you to supply a default answer in a required field that will be invalid, forcing the user to select a valid answer. An optional text field can be added to the select field for a custom or "other" answer, but you may only flag one answer to correspond to the text field.
- Multiple Select Box - This is identical to a select box, except that the user completing the survey can select multiple answers. The way in which this is done varies between platforms, but on a windows machine the user must hold down control or shift while selecting multiple answers. Once this type is selected, another option (Number of Answers) appears that you can configure. This allows you to optionally force the user to select in a fixed number of answers, at least X number of answers, at most X number of answers. An optional text field can be added to the select field for a custom or "other" answer, but you may only flag one answer to correspond to the text field. You may also choose the size of this multiple select field in the Select Size field that appears when a Multiple Select Box question type is chosen.
- HTML Content - Although not actually a question, this type allows you to place any HTML or Text content into your survey where needed. For instance, you could create an HTML Content type at the top of your survey followed by a page break which would create introduction page that can describe the survey. You can also insert images, legends, etc. using this question type. This type will be omitted from exported and printer-friendly results.
- Required
If this field is set to Yes, the user completing the survey will be forced to supply a valid answer for this question before they can move on to the next page or submit the survey. If you wish to make a certain question optional, simply set the Required? field for that question to No.
- Select Size
When the Multiple Select Box question type is selected, you can enter the size of the multiple select form element. Enter an integer greater than 1 to increase the number of answers the user will see at any given time. The number entered corresponds directly to the number of answers the user will see without scrolling within the multiple select field.
- Instruction Text
In some cases, you may wish to have question-specific survey instructions appear in a paragraph of its own right above the question. Although this could be done simply by using HTML in the Question field, it creates for very long questions in the question editor and could have consequences if auto-numbering is used. This is especially true in cases where you wish to have instructional text appear above a group of questions. In that case, simply use the Instruction Text field for the top question in that group and mention that the instructions apply for the following questions. This option is only available from the Advanced Question Editor Interface.
- HTML Content
This appears only for the "HTML Content" question type. This is where you enter the HTML or text that you wish to have appear within your survey.
- Question Text Style
Enter a CSS style here to manipulate the look of the question text. For instance, if you entered the following in the field:
font-family: verdana; font-size: 12px; color: green;
The question text for this specific question would appear green in the typeface of Verdana and be 12 pixels tall, such as:
What is your question text?
Any styles entered here will override similar styles that may have been set survey-wide on the Survey Editor in that Question Text Style field.
To find out more about CSS styles, go to .
- Answer Choices
If you have chosen a Question Type of Radio Buttons, Check Boxes, Select Box or Multiple Select Box, a field for Answer Choices will appear. This field contains a listing of all of the current answers, the ability to change the order of, modify or delete the current answers as well as add additional answers. The following description will guide you through the functionality of this field:
The largest input area in Answer Choices field is a multiple select field that displays all of the current answer choices. You can change the order in which the answers will appear under the question by using the Up and Down Arrows located to the right of the select box. Simply click on the answer you wish to move and then on the arrow pointing in the direction you wish to move the answer.
To add a new answer into the current question, you should type the answer into the text field that initially says "Add answer choices here." Once you have typed in the answer as you wish for it appear in the survey, you can either hit enter or click on the "Add Answer" button in order to add it to the list of Answer Choices. If you wish to have a text input field associated with the answer choice you are adding, simply click on the "Add with Textfield" button. The user of the survey will then have the option of filling in a custom text response when that specific answer is selected.
When adding an answer, you will also have the option of making it a pre-selected choice for the user taking the survey. This option appears a checkbox next to the word "Selected?". If you check that field, the answer will already be selected or checked when the user takes the survey. In this way, you can provide default answers or choose which answer you wish to have selected by default. In the case of a Select Box or Multiple Select Box field, you will also see an option for "Selectable?". This allows you to set a default field in your select box, such as "Choose an Answer" and then make it both selected and unselectable. In this case, the when the user takes the survey, they will see "Choose an Answer" already selected in the Select Box and will be required to switch the answer from the default to a valid "Selectable" value.
If you wish to modify the text of an answer, click on the answer you wish to change. The answer text will appear in the text field and you can then edit it. Once you have modified the answer to your satisfaction, click on the "Modify" button.
To remove an answer from the Answer Choices simply select the answer you wish to remove and then click on the "Delete" button. Doing so will remove the answer from the current question.
PLEASE NOTE: Removing an answer choice from an active survey when results have already been submitted can cause major problems in your ability to view the results a user has submitted.
- Default Answer
You can specify a default text answer for question types of Text Field and Text Area. The default answers are displayed within the text fields when a user takes the survey.
- Number of Answers
If you have chosen a Question Type of either Check Boxes or Multiple Select Box, the field Number of Answers will appear in the Advanced Interface of the "Add/Modify a Question" form. Since the check box or multiple select types allow the user submitting the survey to select multiple answers, this field allows you to control exactly how many answers the user can make. It has the following options:
- Any Number - Selecting this value, which is also the default, will allow the user completing the survey to select as many or as few responses as they wish. Of course, if the field is marked as Required the user will still be forced to mark at least one valid answer.
When any of the following non-default options are selected, you should enter an integer in the textbox to the right of the select field to indicate the number of answers that should apply.
- Exactly - When this is selected and an integer supplied in the field to the right, the user will be required to fill in exactly that number of answers before they can proceed to the next survey page or submit the survey. If Required is set to "No" they can also proceed by filling in 0 answers.
- At Least - When this option is selected and an integer supplied in the field to the right, the user will be required to fill in at least that many answers to proceed. They will also be allowed to fill in more than that number. If Required is set to "No" they can also proceed by filling in 0 answers.
- At Most - When this option is selected and an integer supplied in the field to the right, the user will be required to fill in at most that many answers to proceed. They can also fill in fewer. If Required is set to "Yes" for the question, they must mark at least one valid answer.
- Number of Columns
This field appears only under the Advanced "Add/Modify a Question" form when the Question Type is either Radio Buttons or Check Boxes. By default, the number of columns is 1 unless this field is set to an integer higher than 1. If the number of columns is greater than 1, your answer choices will be placed into multiple columns.
- Answer Input Style
This field allows you to enter any CSS style definition that you wish to have applied to the table cells (<TD>) that surround answer input fields such as radio button, checkboxes, select boxes and text fields. It should be noted that this style will apply to the surrounding cells, not the input fields themselves. To affect the input fields themselves you should read about Text Input Style for textfields and textareas and Answer Text Style for select boxes (single and multiple). Radio and checkboxes cannot currently be altered using CSS.
You can also specify survey-wide defaults for Answer Input Style within the Survey Editor.
- Answer Text Style
In this field you may enter any CSS style definition that you wish to have applied to all answers within this question. If you wanted to have your answers all appear in a red, Arial font of size 12px, you would enter:
color: red; font-style: Arial; font-size: 12px;
This would then cause your answer to appear as:
My first answer.
The style definitions will be placed inside of the <TD> that surrounds each answer. You can also specify survey-wide defaults for Answer Text Style within the Survey Editor.
To find out more about CSS styles, go to .
- Text Input Style
In this field you may enter any CSS style definition that you wish to have applied to all text field answer inputs (text fields and text areas) with the current question. If you wanted your 'Other:' text field or your text area input to have a width of 300 pixels and no shading, you could set this to:
width: 300px; border-left: 1px solid black; border-right: 1px solid black; border-top: 1px solid black; border-bottom: 1px solid black;
That would yield a text field for this question's answers that look like:
The style definitions will be placed inside of the individual input fields for each answer input they apply to. You can also survey-wide defaults for Text Input Style within the Survey Editor.
To find out more about CSS styles, go to .
- Text Input Attributes
Within this field you can specify any attributes of a text field or text area for this specific question. For instance, if you have chosen a Question Type of "Text Area" you may wish to fill in the Text Input Attributes with:
COLS=30; ROWS=3
That would cause your text area input field for this specific question to appear as:
- Display in Summary
On the survey results page, after selecting a survey, you will be presented with a list of all completed surveys submitted so far. Included in this list will be the date and time of submissions as well as either the IP or Email address of the user who completed the survey.
Setting the Display in Summary? field to "Yes" for an individual question will cause the answer to that question to appear in the list of completed surveys. Since each survey in the list appears on one line, you should be selective about which questions you have displayed in the summary so that you do not run out of room.
From the survey summary, the date and time of each submission will be linked to that individual user's survey so that you can access all responses by that user.
4.2) Previewing a Question
You may preview a question at any time once it has been added to a survey. This can be done from within the Question Editor. Highlight the desired question and click on the Preview button below the list of questions. This will open a new window displaying that question.
4.3) Deleting a Question
You may delete a question by selecting it from the list of questions and clicking the Delete button below the list. A prompt will appear asking you to verify the deletion. This process cannot be un-done.
4.4) Changing Question Order
You can change the question order by moving individual questions. Select the question you want to move and click the arrow buttons to the right of the question list to move the question up or down. You can also use this same process to move a page break up or down in the question list, effectively changing where the Next buttons appear throughout your survey.
PLEASE NOTE: After changing the question order, you must click the Save Order button to make the changes permanent.
4.5) Create Page Breaks in Question Order
You may not want to have all of your survey questions on one page. Inserting a page break will move all questions listed after this page break onto a separate page. In this way, you can create a multiple-page survey for your users so that they only see a limited number of questions per page.
To insert a page break into your survey, click on the Add Page Break button below the question list. This will add a page break at the end of the current list. You may move its position in the list in the same way you would change the Question Order. Select it and use the arrow buttons to the right of the question list. After adding a page break, you must click the Save Order button to make the changes permanent.
PLEASE NOTE: After changing the question order, you must click the Save Order button to make the changes permanent.
5) Survey Results
If you are creating surveys for your users, one of the most important things is going to be interpreting and viewing the results. perlQuestionnaire excels at this task, offering you many ways in which you can view the information, even allowing for customized summaries. To get started, you should click on the "Survey Results" tab that can be found at the top of the perlQ administration panel. Once you are there, you will need to select a survey for which you wish to view results. This is done in the same way as for the Survey Editor.
perlQuestionnaire allows you to make survey results public. Doing so allows your visitors to view question results using the table of contents, pagebreaks or all questions at once. This brings the power of complex internet polling software to perlQuestionnaire, offering even further flexibility. Your users will not, however be able to view individual survey results for each user.
User survey results will be shown on the same template that the survey itself has been shown on, allowing you to easily integrate this data into your existing site design.
5.1) Selecting a Survey
Once you have selected a survey, you will see button(s) appear beneath it. The screen will now look like one of the following two screenshots:
 | Figure 5-01 - Survey Results: Select Survey (Using Email Verification) |
 | Figure 5-02 - Survey Results: Selected Survey (No Email Verification) |
Figure 5-01 displays the buttons that will be available if your survey includes a user restriction of Email Verification.
- Verified Results
This will show you the results, on a question-by-question basis, for all users who have verified the email address they have attached to the results. After completing the survey they were emailed a verification link. If the email address they gave was valid and they followed this link, their results will appear in this section.
- Unverified Results
This section displays the results, on a question-by-question basis, for all users who have not yet verified their results. This means that either the email address they provided did not work or they chose not to follow the verification link that was sent to them upon survey completion. These responses could still be valuable, and therefore, they are made available through this button.
- All Results
This button will display, on question-by-question basis, the results for all surveys, both verified and unverified.
If the survey you have selected to view results for did not have a user restriction of Email Verification, then the only button that will appear is:
- View Results
This button will display, on question-by-question basis, the results for all surveys.
After clicking one of these buttons you will be taken to the results on a question-by-question basis. More information about this view can be found in Viewing Question Results. If you wish to view results on a survey-by-survey basis, you should look at the Survey Summary which allows you to view and remove an entire survey response for an individual.
5.2) Survey Summary
 | Figure 5.2-01 - Survey Summary |
After selecting a survey, the window will refresh, displaying a Survey Summary on the lower half of the page (see Figure 5.2-01 above). The summary includes a list of the survey responses, the date it was completed, and user identification information. If Email Verification was used, the user identification information will be the address they supplied. Otherwise, an IP address for that respondent will be shown. It will also display the answers to any questions you marked in the Question Editor to show in the Survey Summary. You may click the date to open a new window displaying the survey with their answers.
The number of responses shown in this summary can be configured, and if the total responses overflows, there will be links at the bottom of the summary to view the next page of data.
5.3) Viewing Question Results
 | Figure 5.3-01 - View All Results |
You can view the results of survey responses on a question-by question basis by following the directions in Selecting a Survey. Once a category of results has been selected with one of the buttons, there are three methods of viewing the results and statistics (shown in Figure 5.3-01 above):
- Table of Contents
You may view statistics for each individual question by clicking on Table of Contents. This will list each question in the survey and allow you to view the results and statistics for each one by clicking on the question.
- View with Pagebreaks
Selecting this view will display the results for each question on a page by page basis with a similar structure to the way the users completed the survey. After viewing one page of question results and statistics you can then proceed to the following pages by using the "Next" button.
- View All Questions
You can view the statistics for all questions in your survey at once by clicking on View All Questions. This will display the statistics for every question in your survey on one page. This is ideal for short surveys, but could be a lot of information on one page if your survey is very long.
When viewing the results for a question, you should note that text answers are displayed in a popup dialog that allows you to read and scroll through all of the text responses to a specific question.
 | Figure 5.3-02 - View Question Results |
5.4) Deleting a Survey Response
You may delete a survey response by accessing the Survey Summary window. Click on the circle with the red X to delete the survey response. A prompt will appear asking you to verify the deletion. This process cannot be un-done.
5.5) Downloading Survey Results
You can download the results of a survey in several different formats. Once you have selected a survey in the Survey Results portion of the Admin, you will see a screen that looks like:
 | Figure 5.5-01 - Download Survey Results |
perlQ currently supports the following download options for your results:
- CSV (Comma Separated Value)
The comma separated file format is one of the most popular methods of exchanging data between different programs. This can be read in by many popular software programs such as Microsoft Excel and Access. Each survey response is placed on one line (unless the results contain newlines themselves), with each answer separated by commas (and enclosed in double quotes if necessary). There is also a header row on the data that contains the column names (such as "IP Address" or the question that was asked). Downloading this file and opening it with Excel or some similar spreadsheet application will allow you to manipulate and view the data in even further ways.
- XML (eXtensible Markup Language)
You can download survey results in valid XML, which is similar to HTML. This format is meant to be easily read by humans or machines (such as a program) and can be combined with style sheets to format the results to your liking.
A brief description of the format of our XML file can be found in the Additional Information: XML Format section of this document. Warning: This file can become very large with many survey results, as the questions and answers are shown for each response.
- XML Condensed (eXtensible Markup Language; Machine Readable)
This representation of the survey results is also in valid XML, but is often around 25% the size of the above XML format. This format is not meant to be easily read by humans, but contains all of the survey information, including page breaks. This would allow you to use this file if you are planning on building applications to parse your results. It refrains from repeating the question and answer names, and supplies the data in a much more concise format. Further information on the format of this document can be found in Additional Information: XML Format.
- SQL (Structured Query Language)
If you choose to download the results in the SQL format, you will end up with a series of INSERT statements which you can use to place your data into the appropriate SQL tables. Executing every INSERT command listed in the file will replicate your survey data into another database, assuming you have created the appropriate tables. It will insert data into perlQSurvey, perlQQuestion, perlQUser and perlQAnswer, as these tables are defined in the Manual Installation section of this document. Because the answers remain unprocessed and difficult for a human to decipher, this is mostly useful for backing up a single survey along with all results. To backup the data in a perlQ compatible format, check out the 'perlQuestionnaire Backup Format' listed below.
- Processed Excel Results for Graphing Purposes
We have also included an option that allows you to download the results processed into a basic Excel compatible format (simple HTML tables). It displays the results for all multiple choice questions with tabulated results from which you can easily create charts and graphs. No results for textfield or textarea answers will be shown.
- perlQuestionnaire Backup Format
This file will contain all of your survey questions and results should you ever find the need to restore this data due to a new installation, a corrupted database or a crashed hard drive. You can also backup your entire perlQuestionnaire database if you wish. Both the backup and restore procedures are detailed more in the Configuration section of this document. Keep in mind that this is the only file format listed here that disregards whether you click on 'Verified', 'Unverified' or 'All' results on an email verified survey. All data from the survey will be backed up regardless of the button clicked.
If your survey is using email verification of survey responses, you will notice three buttons to download either the 'Verified Results', 'Unverified Results' or 'All Results'. Otherwise, the only button will be 'Download Results'. These options all perform as explained in Selecting a Survey, except that they cause you to download the results in the specified format, rather than viewing them through your web browser.
6) Configuration
Clicking the "Configuration" tab at the top of the perlQ Administration panel allows you to setup various defaults and customizations for the perlQ program. This is also where you should go to change your password. The administration screen looks like:
 | Figure 6-01 - Administration Configuration |
6.1) Set Administration and Survey Defaults
- Admin Language:
The Admin Language field allows you to select the language that you wish to be used throughout perlQ Administration screens. It is possible that you will have a wider selection of languages for individual surveys than you do within the admin. This is because it takes significantly more work for the translator to convert the entire admin interface than it does to convert only the publicly visible text strings.
Selecting your administration language will also cause perlQ to find translated images and help files if they are available in that specific language pack. In the case that the images or help files don't exist, english ones will be used instead.
NOTE: This field only appears if you have more than one language available that has translations for the text strings used in the administration panels
The program checks in your perlQ/languages directory in order to determine what languages are available for use in your survey program. Removing the files from this directory will cause perlQ to stop functioning properly. You can learn more about translating perlQ into your language below.
- Default Template:
You can select the template that you wish to be used as your default. This will be used in the following three places:
- Any access to the perlQ/index.cgi file will use this template. When this file is accessed, it will generate a list of the currently active surveys.
- Any illegal or error access to fillsurvey.cgi not related to a specific survey will use this default template.
- When creating a new survey, the Default Template will be selected as the template for that survey. You can always modify what template a specific survey is displayed in.
You can download more templates for perlQ at http://www.chumpsoft.com/products/perlq/.
The program checks in your perlQ/templates directory in order to determine what templates are available for use in your survey program. Removing the files from this directory will cause perlQ to stop functioning properly. You can learn more about creating your own templates below.
- Default Language:
The Default Language field allows you to select the language that you wish to be used as your default. It was introduced in perlQ v2.0 and will only appear if you have multiple languages installed. The default language will be used in the following three places:
- Any access to the perlQ/index.cgi file will use this language. When this file is accessed, it will generate a list of the currently active surveys.
- Any illegal or error access to fillsurvey.cgi not related to a specific survey will use this default language.
- When creating a new survey, the Default Language will be selected as the language for that survey. You can always modify what language a specific survey uses.
NOTE: This field only appears if you have more than one language available that has translations for the text strings used in public surveys, results, etc.
- Cookie Domain:
The Cookie Domain allows you to set a specific domain name for perlQ to use when setting cookies. This can be extremely important to prevent a loophole in cookie restrictions for users taking a survey.
If you fail to set this, cookies will simply be set under the domain they are accessed. This means that a user could first complete the survey at yourdomain.com and later complete it again at www.yourdomain.com even if you have cookie restrictions enabled.
To correctly set this field, you need to use at least two periods in the domain name, such as '.yourdomain.com'. This will allow cookies to be sent to the script even if they were set from www.yourdomain.com or a similar other name. Certain extensions, such as .us or .uk will require three periods in the domain name to properly function.
- Sendmail Path:
- SMTP Server:
perlQuestionnaire allows you to choose between two methods of sending email when you wish to use "Email Verification" as a Survey User Restriction. If neither of these items is completed, you will not be able to use Email Verification.
The Sendmail Path can be used on Unix based systems when you have access to the sendmail program to send messages. When you run the perlQ installer, perlQ will attempt to look in two common locations (/usr/sbin/sendmail and /usr/lib/sendmail). If not found, you may need to contact your system administrator in order to get the correct path and manually enter it here.
The SMTP Server is a domain name that you will be allowed to send email messages through. You must also have installed the in order for this to work. If you are unsure of your SMTP Server name, please contact your server administrator to see if you have access to one.
If you are unsure which you should use, and the perlQ installer does not find your sendmail path, please contact your server administrator.
- Installed in cgi-bin:
perlQuestionnaire has been designed to function on servers using both ExecCGI and cgi-bin methods of CGI execution. In the former case, typically any file ending in .cgi will be executed. These files can then be placed in any directory on your web server. This has largely replaced the use of cgi-bin directories. However, some people are still required to place all of their executables into a "cgi-bin". This is a directory (not always named strictly cgi-bin) where all executables are placed. The file extensions then become unimportant, and any file in this directory is executed.
perlQ needs to know whether your program is installed in a "cgi-bin" or in something resembling the ExecCGI method. In the former situation, perlQ will be required to route all non-CGI files (including every image, css file, etc.) that are included in the perlQ distro through a helper program called img.cgi that will allow these files to be accessed within a cgi-bin. This can lead to some loss in efficiency since the Perl interpreter will now have to be invoked and serve up every image file and css file that is within the perlQ/ directory. If you notice this causing extreme lag, you can change the paths for images in your template to absolute URLs and move the images to a place outside of the cgi-bin on your server.
In case you are uncertain whether perlQ is installed in a "cgi-bin" style directory or not, we have provided a mechanism which attempts to display a hint on the installation page. A table cell is created that contains a green background image and a red foreground image. If you are installed into a "cgi-bin", the red foreground image will fail to load, and only the green image will show up. You should then answer "Yes" to "Installed in cgi-bin". However, if the red image loads up, you will want to answer "No" so that perlQ does not have to route image, css and html files through a CGI program every time they are loaded.
If you have any further questions about whether you are in a cgi-bin or ExecCGI type of setup, you should ask your server administrator. Or, simply test it out. If you answer "No" to this question and your interface continues to look and work properly, it is best to leave it at "No." However, if images begin failing to load, you will need to set this at "Yes."
- List Active Surveys:
Inside of your base perlQ directory, you will find a file called index.cgi. If List Active Surveys is set to "Yes," this page will contain a list of all of your active surveys along with their descriptions. This is useful if you wish to allow your users to see all of the current surveys that are available. The feature can be turned off by setting List Active Surveys to "No."
If the fillsurvey.cgi file (this is what users complete your surveys with) is accessed without any arguments, it will be redirected to index.cgi in your base perlQ directory.
- Editor Interface:
Use the Editor Interface configuration to set whether you wish to see the Advanced or Basic versions of the Survey Editor and Question Editor by default. You can always access either interface when adding or modifying a specific survey or question, so you should set this to the format you most often wish to use.
- Admin Timeout:
If this field is set to a positive integer greater than "60" then an administrator who is idle for longer than the value of Admin Timeout will be automatically logged out. This value represents the time in seconds. This helps to insure that if an administrator leaves his computer with the perlQ admin open, he will be logged out after a certain amount of time.
To turn this feature off, simply enter "0" into the Admin Timeout field and the administrator will no longer be logged off due to idle time. This feature will actually be turned off if the integer is less than 60, to be sure that you always have time to change the value after logging in.
Note that you will have to login to the perlQ admin every time you open your web browser, as the login is not stored once you close your browser.
- Summary Display:
When you access the Survey Results for a specific survey, you will be shown a list of completed entries sorted by Date and showing the IP or Email Address of each respondent as well as any answers to questions you marked Display in Summary within the Question Editor.
The Summary Display field on the Configuration page determines how many of these survey summaries are shown per page. The default number is 20.
- Text Input Display:
When you View Statistics for a specific survey, the results for each question will be shown in detail. When you have a lot of survey submissions, the survey results for a text input field would be very lengthy, as each response will be different. The Text Input Display value specifies how many answers will be shown on the statistics page for a question before you are prompted to "See More..." This makes the size of the statistics/results more manageable. The default for this value is 2.
Once this value is exceeded, you can use the "See More..." link to view the remaining results. The number of responses per page in the popup window for "See More..." is controlled by the Popup Display value.
- Popup Display:
If the Text Input Display value has been exceeded when viewing statistics for the results of a survey, you will be prompted to "See More..." Once you click this link, it will popup a window that shows you the rest of the results to that specific question in the survey.
The Popup Display number specifies how many results are shown on each page of this popup window. The default is 20.
6.2) Change Administrator Password
If you wish to change the perlQ admin password, you will need to enter the Configuration and complete the following three fields. Once this has been done, you should click the Change Password button:
- Current Password - This is the current perlQ admin password that you used to login. We require you to enter it to ensure someone doesn't find this window left open and change the password without you knowing.
- New Password - This is the new password you wish to login to perlQ administration with.
- Retype Password - We require you to re-type the password to ensure no typos were made, since you cannot see the password as you enter it.
You do not need to complete any of these three fields to modify other options within the perlQ Configuration. NOTE: When changing your password you can also update the other configuration options for perlQ.
6.3) Backup Database
perlQuestionnaire allows you to backup and restore your perlQ database. This is very useful in case you ever run into a corrupted database or your hard drive crashes. Using the database backup feature, you can be re-installed and running in minutes, without having lost any of your data prior to your last backup. Backing up your database can also be an excellent idea when you are upgrading, in the slight chance something should go wrong.
perlQ allows you to backup the entire database or a single survey and all results to one file. When clicking on the "Download Data" button, you will be prompted to save a file with a .perlQ extension to your machine.
When backing up a single survey, your perlQ configuration information will be omitted. A backup of the entire database, however, will store all of your perlQ configuration in the downloadable file allowing you to restore your installation exactly as it appears at that moment. The exception to this is your perlQ password, which will not be stored in the backup. Whenever restoring from a perlQ backup, your password will remain unchanged.
You can also use the survey backup feature to share a survey and all associated results with a friend who also uses perlQ. However, if you would prefer to share the survey and questions without the results, you should look into the Export and Import features on the Survey Editor page.
6.4) Restore Database
perlQuestionnaire allows you to backup and restore your perlQ database. This is very useful in case you ever run into a corrupted database or your hard drive crashes. After you have backed up your database, you can be re-installed and running in minutes, without having lost any of your data prior to your last backup. You can import survey results in two ways:
- Restore Data File
This line allows you to upload a perlQ backup file and restore your database using that file. Simply click the "Browse..." button find your perlQ backup ('backup_YYYY-MM-DD.perlQ' if you have downloaded all data). Then select your Restore Behavior and click the "Restore Database" button to have your backup restored into the database.
- Restore From URL
This field also allows you to restore your database from a perlQ backup file. However, using this row gives you the ability to type in a URL to the location of your perlQ backup file. This can come in useful on occasions where your backup file is greater than the max file upload limit imposed by your server or if file uploads aren't working for some other reason. Simply type in the URL to your backup file, select your Restore Behavior and click the "Retrieve Database" button.
Note: Perl requires you to have installed the module in order to retrieve items via a URL.
One critical aspect to a database restore is the method in which you want the restore operation to behave with respect to your existing perlQ data. This Restore Behavior has two possible options and applies to restoring from a data file or URL:
- Restore Data: SAVING ALL Current perlQ Data
This is the default option and ensures that you will lose no data that is currently in your perlQ database. When using this option, no data will be imported to the perlQAdmin table (which covers all perlQ Configuration variables and your password). Only individual surveys, questions, and results will be restored. Furthermore, if any clashing survey ids, question ids or user ids are found, new ones will be generated. This is the safest option for a restore, but will also leave your current data in the database and has the potential to change the URLs you may have used to link to your backed up surveys.
- Restore Data: ERASING ALL Current perlQ Data
WARNING! This action cannot be undone. ALL DATA currently in perlQ will be erased and the data found in your backup file will be the only data placed into the restored database. This script will actually drop the current perlQ tables in your database, erasing all data and then insert all of your backup data. This function has the advantage of maintaining all survey, question and user ids in the data and replicating your database exactly as it appeared when you backed it up. Your password will be kept the same. Keep in mind that you may want to backup your current database before erasing all existing data, in case you later find there was information you wanted.
6.5) Rate this Script
We hope that you are extremely satisfied with the perlQuestionnaire program. We have put a lot of time and effort into making it an extremely flexible and easy-to-use, yet powerful, application. If you are pleased, we hope you can take the time to give us a decent rating at a couple of the premier CGI resource sites. These ratings are displayed to other users and allow them to get a better sense for the quality of our program.
To do so, simply select the rating you feel is appropriate, and click on the "Rate It!" button. Please keep in mind you must do this one site at a time.
Even more powerful, if you are so inclined, is to leave a registered member comment about our script. This gives you a voice to express how you feel about perlQ. To do so, simply follow the links that say "Comment on perlQuestionnaire" and you will be taken to the appropriate page on each site. You may need to register in order to leave your comment. Thank you for your feedback and support!
7) Additional Features
7.1) Templates
To create your own templates for perlQ, you must create new directories and files within the templates directory of your perlQ installation.
- /template_name/
This directory will hold all files related to your template and should be located in the perlQ/templates/ directory.
- /images/
This directory will hold all images required for your template and should be located in the same template's directory. You can locate your image files anywhere, but relative paths in the index.html file will reference within the perlQ/ directory.
- index.html
This is the HTML file that the template references. In the default index.html, all image file paths reference the images/ directory as shown in the directory structure above. The location of the images can be anywhere, but you must use full URL paths when calling the images from anywhere outside of the perlQ/ directory. There are several directives you can insert into the HTML file to include the survey and other data:
- Template Designation
This line must be the first line of your HTML code. It defines the name of the template as it will appear in the select menu for each survey. This line will not be displayed once the survey is rendered to the user's screen:
<!--// TEMPLATE: perlQ Default Template //-->
- ::CHARSET::
In order for browsers to properly select a character encoding when using multiple languages, you should include an HTML tag such as the following within the <HEAD> of your template:
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=::CHARSET::">
The value of CHARSET will be defined inside of each individual language file.
- ::SURVEYNAME::
perlQ will replace this text with the Survey Name you have defined in the Survey Editor for each specific survey. In the default template, this is placed in the <TITLE> tags.
- ::CONTENT::
perlQ will replace this text with the survey questions and answers. This tag is required in order to have the survey questions and answers appear on the page.
- ::PAGENUMBER::
Use this tag if you would like text such as "Page 1 of 3" to appear on multi-page surveys. The value of PAGENUMBER will be blank on any single-page survey and will be formatted as specified in each individual language file.
- ::JSCRIPT::
This will import any required JavaScript into the template. The only time this is needed is if your results are publicly viewable, so that the survey can popup extra results over the configured limit for textfields and other inputs. You are free to leave this out if you will not be offering public results in your template.
Also included in the distribution is a Blank Template, which you can use if you wish to integrate your survey into an existing page using Server Side Includes or a PHP call. Using this, only your survey question(s) will be displayed and you can design the result page content to look however you want. To perform the server side include call, you would use code such as:
<!--#include virtual="/path/to/perlQ/fillsurvey.cgi?sid=XX-->
Where 'XX' above should be replaced with the survey ID for the specific survey you are calling. You can also perform an inclusion of this script from within a PHP generated page by using the include function with an absolute URL, such as:
include 'http://www.yoursite.com/path/to/perlQ/fillsurvey.cgi?sid=XX';
Again, you need to replace the actual survey id as well as the correct URL and path to your perlQ directory.
The Dashed Line template is based on a free CSS code from at .
7.2) Languages
perlQ contains easy and flexible way to translate and have available multiple languages for use in both your surveys and the administration panel. The only official support language available and included with the 2.0 release is English. As more language translations are provided by users such as yourself, you can obtain them at http://www.chumpsoft.com/products/perlq/.
Once you have downloaded a language translation, you can unpack it into your base perlQ/ directory and it should go into the languages/ directory, creating a directory specific to that translation. Each individual translation file includes installation help as well.
Translating perlQ into your language:
The process of creating translations has been greatly simplified. The following is the structure of the english language pack. You can modify all or parts of it as follows:
- perlQ/
- language_name/
The first step to creating a new language pack is to create a directory inside of the perlQ/languages directory. The name should be short and representative of the language (in all lowercase, such as french, german, spanish, etc.). All of the translated files and strings will go inside of this directory.
- index.pl
This file contains all of the translated strings for your language, and is the only file required to be in your language pack. You will need to copy the English version from perlQ/languages/english/index.pl over to your new directory, and edit that file to ensure you do not miss any strings. There are several conventions used inside of this file that you must preserve in order for things to work as expected:
- Language Designation
Much like our template system, the first line in your language file serves a dual purpose. The first is to open the Perl comment using # and the second is to alert perlQ to what language this file represents and what specifically has been translated. It should look something like:
# LANGUAGE: English: PUBLIC|ADMIN|IMAGES|HELP
It is very important to maintain the formatting shown above. 'English' is the language name that will be shown inside of the admin for easy identification of this translation. PUBLIC, ADMIN, IMAGES and HELP specify what portions of perlQ have been translated in this language and should be separated by | (pipe) without any spaces in the middle. You may change the text 'English' to specify your language and also remove any of the all caps words that you do not intend to translate. You should not translate the text such as PUBLIC or ADMIN, however.
- PUBLIC
In order to have a langauge translation, your file must contain at least PUBLIC. This represents that you have translated the text strings within index.pl that have the potential to be shown to your visitors through surveys, confirmation emails, etc.
- ADMIN
If you would like to have your administration screens and editors appear in your language, you may also translate the administration portion of the index.pl file. There is substantially more text involved in the admin as opposed to publicly viewable, and this text will never be seen by visitors to your site.
- IMAGES
Once you have translated the administration text, you can send us the file and we will attempt to make images of this text in your language. This will allow even the images that appear within perlQ to be translated into your own language. If no image files are translated, english ones will appear instead.
- HELP
HELP is the least likely to appear in your translation. In order to include this, you must translate all of the files found in the help/ directory of the english language, nearly 70 html files! These files are used as popup screens within the admin if the user clicks the help icon next to an item.
- CHARSET
Near the top of the index.pl file, you will see:
$perlQlang{'CHARSET'} = 'iso-8859-1';
This character set will define to the web browser how it should render your pages. You must place the appropriate charset into the value of this variable.
- $perlQlang{'__'}
The rest of the file, you will see a large number of text strings being set into the perlQlang associative array. It is important that you change the text inside of the quotes that appears after the equal sign. The variable names must not be translated, as perlQ uses these to extract the correct string from your file.
In some places, you may see something like %s or %d appear. In these cases, this indicates that another string may be placed into your translation at run time. For instance, the following appear in the public section of the language file:
$perlQlang{'PageNumber'} = 'Page %s of %s';
$perlQlang{'SurveyExpired'} = 'The survey <B>%s</B> has expired.';
In the above examples, when perlQ is run and this string is called upon, the appropriate values will be placed inside of the string. For instance, if you are on Page 2 of 10, a 2 will be substituted for the first '%s' and a 10 for the second. Likewise, the survey name you have defined for the specific survey that is expired would appear in the second string. More information on what will be replaced into each string can be found within the english language translation. If you were translating the second string to Spanish, it might read something like:
$perlQlang['SurveyExpired'] = 'El cuestionario <B>%s</B> ha expirado.';
- images/
In most translations, you will not feel the need to include images. These images would only appear within the admin and therefore are usually unnecessary. However, if you would like a totally language immersive experience inside of perlQ and choose to convert the administrative text, you may submit the language file to us and we will attempt to create images with the correct text for your translation. If you choose not to include languages, do not worry, perlQ is smart enough to find the english ones and use them instead. If your language translation has no images, you should omit this directory and also remove the 'IMAGES' from the first line of your index.pl file.
- help/
Rarely translated, this directory contains all of the popup help screen text that appears when you click on the '?' images within the admin screens. Most people will not want to expend the time to translate these files as you can probably read english if you have managed to buy our product in the first place. However, we leave the option open to you if you wish to create the help screens in your own language! If your translation has no help files, you should omit this directory and also remove the 'HELP' from the first line of your index.pl file.
If you have any further questions about how to translate perlQ into your language or use one of the existing translations, please let us know!
7.3) Manual Installation
In almost all cases, the Automatic Installation should setup perlQuestionnaire to run on your web site. In the case that it fails, you can also manually install this script. After extracting all files from the distribution package, as described in Getting Started, you will have the following directory structure:
perlQ/
CHANGELOG
INSTALL
LICENSE
README
admin/
confirm.cgi
docs/
error.cgi
fillsurvey.cgi
img.cgi
index.cgi
install.cgi
languages/
perlQMod/
previewquestion.cgi
stats.cgi
templates/
verify.cgi
view.cgi
viewoption.cgi
Within each of the directories above, you will find many other files and directories. As long as you move the perlQ base directory around as a unit, it will work as expected.
NOTE: You must make sure all .cgi files in both the perlQ/ and perlQ/admin/ directories are chmodded to '755' (executable/readable) if you are on a Unix webserver.
Creating MySQL Tables for perlQ
Now that you have placed this perlQ directory into your web space, you must also create the tables that it will use in MySQL. To do so, you will need access to your MySQL username, password and database. If you are unfamiliar with this data, please ask your hosting provider to supply it. You must now create the following tables. Using the MySQL client, you can simply copy and paste the following SQL statements. Please note, the automatic installer will create these tables and populate them with some simple data to test your setup.
CREATE TABLE perlQAdmin (
perlQID BIGINT UNSIGNED NOT NULL,
Version CHAR(10) NOT NULL,
Passwd VARCHAR(20) NOT NULL,
Template VARCHAR(50) NOT NULL,
Language VARCHAR(50) NOT NULL,
AdminLanguage VARCHAR(50) NOT NULL,
SendmailPath VARCHAR(100) NOT NULL,
SMTPServer VARCHAR(100) NOT NULL,
SummaryLimit INT UNSIGNED NOT NULL DEFAULT 10,
TextareaLimit INT UNSIGNED NOT NULL DEFAULT 5,
PopupLimit INT UNSIGNED NOT NULL DEFAULT 5,
AdvanceInterface ENUM('y','n') NOT NULL DEFAULT 'n',
InCgiBin ENUM('y','n') NOT NULL DEFAULT 'y',
ListSurvey ENUM('y','n') NOT NULL DEFAULT 'y',
TimeOut BIGINT UNSIGNED NOT NULL,
CookieDomain VARCHAR(255) NOT NULL
);
CREATE TABLE perlQSession (
SessionID VARCHAR(255) NOT NULL,
RecentTime BIGINT UNSIGNED NOT NULL
);
CREATE TABLE perlQSurvey (
SID BIGINT UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
Name VARCHAR(255) NOT NULL,
AddDate DATETIME NOT NULL DEFAULT '0000-00-00',
SurveyUsers CHAR(3) NOT NULL DEFAULT '000',
SurveyResults TINYINT NOT NULL,
Width VARCHAR(255) NOT NULL,
Indent INT UNSIGNED NOT NULL DEFAULT 20,
QuestionNumb ENUM('y','n') NOT NULL DEFAULT 'y',
QuestionStyle VARCHAR(255) NOT NULL,
AnswerInputStyle VARCHAR(255) NOT NULL,
AnswerTextStyle VARCHAR(255) NOT NULL,
AnswerStyle VARCHAR(255) NOT NULL,
ErrorStyle VARCHAR(255) NOT NULL,
VerifyEmail TEXT NOT NULL,
EmailFrom VARCHAR(255) NOT NULL,
EmailSubject VARCHAR(255) NOT NULL,
Template VARCHAR(50) NOT NULL,
Language VARCHAR(50) NOT NULL,
OnComplete TINYINT NOT NULL,
RedirectURL TEXT NOT NULL,
Completed TEXT NOT NULL,
Description TEXT NOT NULL,
AdminNotes TEXT NOT NULL,
Active ENUM('y','n') NOT NULL DEFAULT 'n',
StartDate DATETIME NOT NULL DEFAULT '0000-00-00',
EndDate DATETIME NOT NULL DEFAULT '0000-00-00',
AdvanceInterface ENUM('y','n') NOT NULL DEFAULT 'n',
ResultsWidth VARCHAR(255) NOT NULL,
ResultsBorder VARCHAR(255) NOT NULL,
ResultsAnswer VARCHAR(255) NOT NULL,
ResultsStats VARCHAR(255) NOT NULL,
ResultsGraph VARCHAR(255) NOT NULL,
SubmitImageSrc VARCHAR(255) NOT NULL,
SubmitImageWidth INT UNSIGNED NOT NULL,
SubmitImageHeight INT UNSIGNED NOT NULL,
SubmitImageText VARCHAR(255) NOT NULL,
ResultImageSrc VARCHAR(255) NOT NULL,
ResultImageWidth INT UNSIGNED NOT NULL,
ResultImageHeight INT UNSIGNED NOT NULL,
ResultImageText VARCHAR(255) NOT NULL,
NextImageSrc VARCHAR(255) NOT NULL,
NextImageWidth INT UNSIGNED NOT NULL,
NextImageHeight INT UNSIGNED NOT NULL,
NextImageText VARCHAR(255) NOT NULL,
ResponseNotice TINYINT NOT NULL,
ResponseEmail TEXT NOT NULL
);
CREATE TABLE perlQQuestion (
SID BIGINT UNSIGNED NOT NULL,
QID BIGINT UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
SortOrder INT UNSIGNED NOT NULL,
Question TEXT NOT NULL,
Type ENUM('radio','checkbox','textfield','textarea','select','selectmult','pagebreak','htmlcontent') NOT NULL DEFAULT 'radio',
Mult INT UNSIGNED NOT NULL DEFAULT 1,
QuestionStyle VARCHAR(255) NOT NULL,
Instructions TEXT NOT NULL,
Answer TEXT NOT NULL,
Choose VARCHAR(11) NOT NULL,
DefaultAnswer TEXT NOT NULL,
LargestAID INT UNSIGNED NOT NULL,
ColNumb INT UNSIGNED NOT NULL DEFAULT 1,
AnswerInputStyle VARCHAR(255) NOT NULL,
AnswerTextStyle VARCHAR(255) NOT NULL,
AnswerStyle VARCHAR(255) NOT NULL,
Attributes TEXT NOT NULL,
Required ENUM('y','n') NOT NULL DEFAULT 'y',
Summary ENUM('y','n') NOT NULL DEFAULT 'n'
);
CREATE TABLE perlQUser (
UID BIGINT UNSIGNED NOT NULL PRIMARY KEY DEFAULT 0,
SID BIGINT UNSIGNED NOT NULL,
IPAddr VARCHAR(100) NOT NULL,
BlockDupe VARCHAR(40) NOT NULL,
CheckType CHAR(3) NOT NULL DEFAULT '000',
Email VARCHAR(255) NOT NULL,
Confirm VARCHAR(50) NOT NULL,
EmailConfirm ENUM('y','n') NOT NULL DEFAULT 'n',
CompleteDate DATETIME NOT NULL DEFAULT '0000-00-00'
);
CREATE TABLE perlQAnswer (
UID BIGINT UNSIGNED NOT NULL,
SID BIGINT UNSIGNED NOT NULL,
QID BIGINT UNSIGNED NOT NULL,
Answer TEXT NOT NULL,
UNIQUE uniqids (SID, QID, UID),
INDEX index_uid (UID)
);
You must also create the default administrator account for this installation by inserting the following row:
INSERT INTO perlQAdmin VALUES (1, '2.2', 'password', 'default', 'english', 'english', 10, 5, 5, 'n', 'y', 0, '');
Configuring perlQ and MySQL
After setting up the tables used by perlQuestionnaire, you will need to edit the file 'perlQ/perlQMod/DBInfo.cgi' that is part of the distribution. Inside of this file, you will see 3 lines that look like:
$dsn = 'DBI:mysql:database=perlQ;host=localhost';
$user = '';
$password = '';
You must fill in the proper values for all of these items according to your MySQL setup ($dsn must be formatted according to the DBI.pm specs). If you are uncertain, please contact your web hosting provider for the necessary information.
Removing Installation Files
Since you have chosen a manual installation, you can now also delete the file 'perlQ/install.cgi'. This is a very important step, as leaving this file in place could allow a hacker to re-install the perlQ files.
Completion
Your perlQuestionnaire program should now be successfully installed. Proceed to Logging in as Administrator to begin using perlQ.
7.4) XML Format
perlQuestionnaire offers you the ability to download your survey results in several formats. Two of these formats use the eXtensible Markup Language. The following is a brief description, using our Document Type Definitions (DTD):
XML Format
This XML document was designed to be easily read by humans. It can, however, become VERY large as more and more results are entered. For something more compact, you should read into our XML Condensed Format shown further below.
The XML Format we use encloses everything in <survey>. This tag then contains a <name> of the survey, an optional <description> and 0 or more <result> tags. Each <result> tag then contains a <time>, <ip> and <email> tag corresponding to the date completed, the user's IP Address and optionally the user's Email Address (if email verification is being used). The <email> tag will also have an attribute of verified set to 'y' or 'n'. The <result> will also contain 0 or more <question> tags which contain an <asked> tag (supplying you the question that was asked) and 0 or more <answer> tags. Each <answer> contains either a <selected> tag (which holds the text of the answer a user selected from a radio button, select field, etc.), an <entered> tag (which contains any text a user entered into a textfield or textarea) or both (such as a checkbox with a textfield).
The following is the DTD for this XML file:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE survey [
<!ELEMENT survey (name,description?,result*)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT result (time,ip,email?,question*)>
<!ELEMENT time (#PCDATA)>
<!ELEMENT ip (#PCDATA)>
<!ELEMENT email (#PCDATA)>
<!ELEMENT question (asked,answer*)>
<!ELEMENT asked (#PCDATA)>
<!ELEMENT answer (selected?,entered?)+>
<!ELEMENT selected (#PCDATA)>
<!ELEMENT entered (#PCDATA)>
<!ATTLIST survey id CDATA #REQUIRED>
<!ATTLIST result id CDATA #REQUIRED>
<!ATTLIST email verified (y|n) #REQUIRED>
<!ATTLIST question id CDATA #REQUIRED>
<!ATTLIST question type (checkbox|radio|select|selectmult|textfield|textarea) #REQUIRED>
<!ATTLIST answer id CDATA #IMPLIED>
]>
XML Condensed Format
The condensed format is normally about one quarter the size of our human readable formatting. It achieves a smaller footprint by refusing to repeat question names and answer values over and over. Instead, the survey configuration is listed in a <config> tag. This tag contains a <name>, optional <description> and 0 or more <question> tags. Each <question> and <answer> contain id's unique within this survey. The <question> tag also contains the question type as an attribute and the <asked> tag with the text of the question asked. Each question contains one or more <answer> tags which contain an id (referenced later) and the text shown for that answer. If this is a textfield or textarea results, the text will be the default text for that field.
Now that the survey has been defined, each response to this survey will be listed in a <r> tag which contains attributes of id, time, ip, email and verified corresponding to the unique user id, time of completion, IP Address and Email Address (if the survey uses verified email) and whether or not that Email Address was verified. Within each <r> result tag are multiple <a> tags containing this user's answer to each question. Each <a> tag contains an id and qid attribute. This defines the question id and corresponding answer id within that question to the selected choice. If the user entered any text for the question (such as a textfield or textarea) the answer will be contained within the <a></a> tags. If this was a textfield or textarea style question, no id attribute will be available for the <a> tag. You can use a given qid and id within an <a> tag to match the corresponding text value of that answer within the <config><question><answer> hierarchy.
The following is the DTD for this XML file:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE survey [
<!ELEMENT survey (config,r*)>
<!ELEMENT config (name,description?,question*)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT question (EMPTY|(asked,answer*))*>
<!ELEMENT asked (#PCDATA)>
<!ELEMENT answer (#PCDATA)>
<!ELEMENT r (a*)>
<!ELEMENT a (#PCDATA|EMPTY)*>
<!ATTLIST survey id CDATA #REQUIRED>
<!ATTLIST question id CDATA #REQUIRED>
<!ATTLIST question type (checkbox|radio|select|selectmult|textfield|textarea|pagebreak) #REQUIRED>
<!ATTLIST answer id CDATA #IMPLIED>
<!ATTLIST r id CDATA #REQUIRED>
<!ATTLIST r time CDATA #REQUIRED>
<!ATTLIST r ip CDATA #REQUIRED>
<!ATTLIST r email CDATA #IMPLIED>
<!ATTLIST r verified (y|n) #IMPLIED>
<!ATTLIST a qid CDATA #REQUIRED>
<!ATTLIST a id CDATA #IMPLIED>
]>
If you wish to learn more about XML, you should check out:
7.5) Getting Support
When you purchased perlQuestionnaire, you also purchased the ability to contact us for email based technical support any time in the first year of ownership. You can email us at any time at support@chumpsoft.com.
You can also obtain support on the web. Simply go to http://www.chumpsoft.com and sign into our member's area. This is the same area that you entered in order to download this script.
|